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ur tour of the Windows 3.1 com- 
mon dialogs finally brings us to 
the subject of printing and 
printer setup. You may recall 
that during the discussion of the 
ChooseFont common dialog, I 
characterized traditional font 
management under Windows as 



programming voodoo, which I 
define as reliance on poorly documented 
procedures that are invoked ritualisti- 
cally and are prone to failure for reasons 
that are only dimly understood. Well, the 
' 'tricacies of Windows font management 
.e only a foretaste of the surprises that 
lay in wait for you in the area of printing. 

In theory, Windows applications are 
device-independent, and "painting" on 
the printer should be little different from 
painting on the screen. In reality, there 
are many considerations peculiar to use 
of the printer, including (but not limited 
to) the fact that the printer often supports 
different fonts than the screen supports; 
the printer may have higher or lower res- 
olution than the screen; the printer may 
not contain enough memory to support 
all the individual pixels on a page; the 
printer can run out of paper or be taken 
off-hne; the system may support several 
different printers at once; and two or 
more applications may try to send output 
to the printer simultaneously. 

A Microsoft technical writer took 
note of this situation by starting the chap- 
ter on printing in the Windows 3.0 SDK 
Guide to Programming with a little gal- 
lows humor: "In Microsoft Windows, 
your application need not provide any 
printer-specific code; it can simply print 

the eiurent printer." The author then 
proceeded to describe, for 21 pages, ex- 
actly how to write the printer-specific 
code that your application didn't need to 



provide. Of course, we could assume that 
Microsoft was referring to differences be- 
tween brands of printers, rather than be- 
tween printers and other types of output 
devices — ^but even that doesn't make the 
statement true. Windows printer drivers 
are allowed quite a bit of latitude in the 
services they export, and a sophisticated 
graphical application cannot hope to gen- 
erate high-quality hard copy unless it me- 

Ure addition of a comnum 
printer dialog to Windows 

3.1 relieves applications 
programmers of the need to 

design and test elaborate 
printing and setup dialogs. 



ticulously adapts its behavior to the capa- 
bilities of the printer driver. 

BASICS OF WINDOWS PRINTING In Win- 
dows 3.0 and earher, the issue of printing 
is complicated by the rather involved ini- 
tiahzation an application needs to go 
through first. The application must call 
the Windows API function GetProfile- 
StringO to obtain the device= line de- 
scribing the current printer from 
WIN.INI (or open and read WIN.INI di- 
rectly), then parse the hne to extract the 
printer brand and model, the printer 
type, and the printer output port. Once 
the printer is identified, the program 
must create a printer device context anal- 
ogous to but not completely synmietric 
with a display device context, and present 
an elaborate dialog to the user allowing 
him to select the range of pages, the nimi- 



ber of copies, the paper tray, the paper 
dimensions, and so forth. The appHcation 
must also support a setup dialog that al- 
lows the user to reconfigure the printer 
or switch from one printer to another (in 
systems that support multiple printers). 

With the device context in hand, the 
application can proceed to the actual 
business of printing. In Windows 3.0, the 
entire print job had to be framed with Es- 
cape() calls using the STARTDOC and 
ENDDOC parameters, allowing Win- 
dows to serialize printer output and keep 
the pages of one application from being 
interleaved with those of another. (The 
Escape() function is roughly equivalent 
to the DOS lOCTL function; it provides 
a direct channel of communication be- 
tween the application and the printer 
driver.) GDI calls such as TextOut(). 
DravvText(), Rectangle(), and the like 
can be used with the printer DC in the 
expected fashion, but the appUcation 
needs to keep track of page position and 
issue EscapeO calls with the NEW- 
FRAME parameter to eject pages when 
appropriate. If the output is mostly 
graphics, the application may have to seg- 
ment the page into "bands" that won't 
overflow the printer's memory. 

A Windows 3.0 application needs to 
be able to recover gracefully in case of 
a printer error, and must let the user 
abort the printing process at any time. 
This means that the application must con- 
tain a special callback procedure to be 
entered only in the event of a printer mal- 
function; this procedure is expected to 
put up an alert dialog that describes the 
problem to the user and lets him take ac- 
tion. The well-behaved Windows appU- 
cation should also display a free-floating 
dialog with a Cancel button during the 
entire process of printer output; fancier 
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apps audit the name of the file bein? 
printed, the current page number, ai 
other Useful information as well. ^ 

What changes does Windows 3.1 bring 
to this scheme? In general, the latest ver- 
sion of Windows drastically simplifies the 
application grunt work involved with 
printing. For typical applications, the 
catchall Escape() API function is super- 
seded by the new and simpler API func- 
tions StartDocO, StartPage(), End- 
Page(), EndDocO, SetAbortProc(), 
AbortDocO, and SpoolFile(). (The Es- 
cape() fimction is still available for back- 
ward compatibility and for applications 
that need to query printer capabilities.) 
The ChooseFont common dialog has op- 
tions that let the appUcation easily deter- 
mine which fonts are supported for the 
printer, which for the screen, and which 
for both, while the addition of TrueType 
means that the application can leave be- 
hind most concerns about the availability 
(on the printer's end) of unusual font 
sizes or styles, Best of all, the addition 
of a common printer dialog relieves the 
applications programmer of the need to 
design and test elaborate printing and f 
tup dialogs and their supporting callbav 
functions. 

You may well ask. isn't Microsoft's 
spiffing up of printer support in Windows 
3.1 a case of bolting the bam doof after 
the horse is long gone? It's true that few 
Windows programmers are inclined to 
revise and potentially break application 
source code that is already working, even 
if the revisions tend to simplify the code 
and improve maintainability. On the 
other hand, many programs will need to 
be thoroughly overhauled for OLE (ob- 
ject linking and embedding) and develop- 
ers may use that opportunity to incorpo- 
rate support for other Windows 3.1 
enhancements, such as the common dia- 
logs, TrueType, and multimedia. Fur- 
thermore, the new Windows 3.1 common 
dialogs and printing functions are exactly 
symmetric with the common dialogs and 
printing functions of NT/WIN32, so any 
conversion efforts now will be repaid in 
portability later. 

USING PRINTDLGO The common print- 
er dialog, whose code and resources are 
contained (like the other common c 
logs) in the dynamic link library 
COMMDLG.DLL, is actually two dia- 
logs in one. The (X)MMDL(j.DLL entry 
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point is called PrintDlg(). and you call it 
with a far pointer to a PRINTDLG data 
structure that controls various dialog op- 
tions and receives the dialog's results. 
(The fields of the PRINTDLG structure 
are listed in Figure 1.) Here is the skele- 
ton of a typical call to PrintDlg(): 

PRINTDLG pd; 



PrintDlg (&pd) ; 

PrintDlgO returns TRUE if the user suc- 



cessfully completes the dialog and clicks 
the OK button; it returns FALSE if tf 
user clicks the CANCEL button or closes 
the dialog using the system menu, or if 
an error occurs. You can determine the 
cause of the error by calling CommDlg- 
ExtendedErrorO to get the error code. 

The PRINTDLG structure contains 
numerous fields, but many of these can 
be ignored for routine appUcations pro- 
gramming. The crucial items to take 
note of in the PRINTDLG structure 
are the PD_PR1NTSETUP and PD_RE- 
TURNDC bits in the Flags field. If the 
application calls PrintDIg() with the 





The PRINTDLG Structure 


Field Name 


Description 
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Flags 


Contsins various option flags that affect the 




initialization and behavior of the common dialog. 


nFromPagG 


Fir<it nanp tn nrint 


nToPage 


Last pag6 to print. 


nMinPage 


Mintmuni numbsr of pagss that can bG spscifiGd with tho 




From PaQG and To PagG edit controls. 


nMaxPage 


Maximum number of pages that can be specified with the From 




Page and To Page edit controls. 


nCopies 


Number of copies to print 


hinstance 


Identifies the data block containing a custom dialog template. Ignored if 




the PD_ENABLEPRINTTEMPLATEorFR_ENABLESETUPTEMPLATE bit is 




not set in the Flags field. 


ICustData 


SpGcifiGS applicatlon-dGfined data to be passed to the 




function designated by the IpfnPrintHook or IpfnSetupHook fields. 


IpfnPrintHook 


Address of the application's "hook" function for the print dialog. Ignored 




if the PD_ENABLEPRINTHOOK bit is not set in the Flags field. 


IpfnSetupHook 


Address of the application's "hook" function for the printer setup dialog. 




Ignored if the PD_ENABLE SETUPHOOK bit is not set in the Flags field. 


1 p PrintTemplateName 


Points to a string that specifies the name of the resource for a custom 




print dialog template. Ignored if thG PD_ENABLE PRINTTEMPLATE bit is 




not set in the Flags field. 


IpSettiifgrnpisteN^me 


Points to a string that specifies the name of the resource fora custom 




printer setup dialog template. Ignored if tho PD_ENABL£ SETUPTEMPLATE 




bit is not set in thG Flags field. 


hPrintTem plate 


Handle for a mGrnory block containing a custom print dialog template. 




Ignored if the PD_ENABLE PRINHEMPLATEHANDLE bit is not set in thG 




Rags field. 


hSetupTempiate 


Handle for a memory block containing a custom printer setup 




dialog template. Ignored if the PD^ENABLE SETUPTEMPLATEHANDLE 




bit is not set in the Flags field. 



I^re t Rekls of the PHHfrDLG data stmcbire used by the PrintUgO coiiinion dialog. 
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PD^PRINTSETUP flag, the function dis- 
plays a Printer Setup dialog that allows 
the user to configure the printer or 
switch from one printer to another, as 
shown in Figure 2. AH of the necessary 
grubbing around within WIN.INI and 
querying of printer capabilities is buried 
within the common dialog library. Here 
is typical code for presenting the Printer 
Setup dialog: 

PRINTDLG pd; 



memset(5cpd, 0, sizeof (PRINTDLG) ) ;' 
pd.lStructSize = sizeof (PRINTDLG) ; 
pd. Flags = PD_PRINTSETUP; 
PrintDlg(&pd) ; 

If an appUcation calls PrintDlg() with 
the PD_RETURNDC flag, the function 
will display a Print dialog that allows the 
user to enter the range of pages and num- 
ber of copies (see Figure 3). A Setup but- 
ton in the dialog lets the user detour to 
the Printer Setup dialog, if desired. The 
PrintDlgO function then determines the 
type of printer and allocates a printer de- 
vice context. After PrintDlgO returns, 
the program can extract the device con- 
text, number of copies, starting and end- 
ing page numbers, and other options 
from the PRINTDLG data struclure. 
The structure also contains handles for 
memory blocks that contain DEV- 
MODE and DEVNAMES structures, 
which the application can lock down and 
inspect for detailed information about 
the printer(s). Basic code for displaying 
a Print dialog and then calling a routine 
to print a file using the returned device 
context might look like this: 
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PRMTDLG pd; 



memset (&pd, 0, 

sizeof (PRINTDLG) ) ; 
pd. IStructSize = 

sizeof (PRINTDLG) ; 
pd. Flags = PD_RETnRNDC; 
if (PEiatDlg (tpd) ) 
{ 

PrintFile(pd.hDC) ; 
i f ( pd . hDevMode ) 

GlobalFree (pd . hDevMode ) ; 
i f { pd . hDevNames ) 

GlobalFree (pd. hDevNames) ; 
DeleteDC (pd . IiDC ) ; 

} 



Like the other common dialog func- 
tions, PrintDlgO has options that allow 
applications to filter all of the dialog's 
messages with a hook function or to re- 
place the default dialog templates with 
custom templates. The needs of most ap- 
plications, however, will be amply served 
by the default Print and Printer Setup di- 
alogs and message handUng. 

THE DLGDEM04 PROGRAM This issue's 
demonstration program, DLGDEM04 
.C, is yet another version of the DLG- 
DEMO programs printed in the last three 
issues. DLGDEM04 is a clone of the 
Windows Notepad program that relies on 
a multihne edit control for primitive edit- 
ing of a plain ASCII text file. Figure 4 
contains extracts of the source code that 
are relevant to the printing capabilities 
of the program. The complete soiu-ce 
code and executable program can be 
downloaded from PC MagNet. 

Crucial changes in DLGDEM04 are: 
• the addition of Print and Print Setup 
options to the File pop-up menu 
in the resource script DLGDE- 
M04.RC; 

• the addition of the routines 

DoMenuPrintSetupO, DoMenu- 
Print(), and PrintFile() to the 
source file; and 

• the addition of the Print and 
Print Setup menu identifiers and 
the addresses of the DoMenu- 
PrintSetupO DoMenuPrintO 
routines to the table menuitems[] 
in r>T riF»T7\^o/i r* 




figure 3: This is a screen shot of DLGDEM04, which shows the 
Print common dialog. 



identifiers and the prototypes for the new 
routines. 

Let's see what happens when a user 
requests a print operation. Windows pro- 
cesses the user's menu selection and 
sends a WM_COMMAND message with 
the IDM_PRINT identifier in wParam to 
DLGDEM04's main callback routine. 
Frame WndProc(). Frame WndProcO de- 
codes the message using the table mes- 
sages[] and dispatches the message to the 
routine DoCommand(). DoCommand 
decodes wParam using the table men. 
items[] and dispatches the message to the 
routine DoMenuPrint(). 

When DoMenuPrintO gets control, it 
allocates a PRINTDLG data structure, 
initializes it, and calls PrintDlgO to dis- 
play the Print common dialog. If 
PrintDlgO returns TRUE, DoMenu- 
PrintO extracts the printer device context 
from the PRINTDLG data structure and 
passes it to the routine PrintFile(). 
PrintFUeO locks down the memory block 
belonging to the edit control and deter- 
mines the number of lines of text, exiting 
immediately if there's nothing to print. 
Otherwise, PrintDlgO calls GetTextMet- 
rics() to get the vertical cell size (in pix- 
els) of the current printer font, calls Get- 
DeviceCapsO to get the page size in pix- 
els and the number of pixels per logical 
inch in both dimensions, and calculates 
the page margins. This information gath- 
ered, PrintFileO is ready to get to work. 

PrintFileO begins the printing opera- 
tion by calling StartDocO and Start- 
Page() to initialize the printer driver and 
gain control of the printer output stret 
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DLGDEM04.C 

Partial Listing 



// DLGDEM04 - Notepad Clone #4 demonstrating use of Win 3.1 Cctmrnon Dialogs 

// Copyright (C) 1992 Ray Duncan 

// Ziff Davis Publishing Co. • PC Kagazine 



#define WIN31 



if (pd.hDevMode) 

GiobalFree(pd.hDevMode) ; 
i f (pd . hDevNames ] 

GlobalFree(pd.hDevNames) ; 
DeleteDCtpd.hDC) ; 



// free DEVMODE memory block 
// allocated by conmon dialog 
// free DEVMAMES memory block 
// allocated by conimon dialog 
// free printer device context 



#include 'string .h" 
#include "windows .h" 
•include "commdig .h" 
♦include *dlgdemo4 .h" 



// 

// PrintFile - print contents of edit 
/ / context supplied by caller . 



window, using printer ifevice 



struct decodeWord { 
WORD Code; 
LONG CFxn) (HWND, 



WORD, WORD^ LONG); ), 



/ / Structure associates 
// messages or menu IDs 
// with a function 



/ Table of menubar item IDs and their corresponding functions. 
/ 

truct derCodeWord inenuitems[] = { 
IDM_MEW, DoMenuNew, 
IDM_OPEN, DoMenuOpen, 
IDM_SAVE , DoMenuSave , 
IDM_£;aVEAS, DoMenuSaveAs, 
IDM„PSETUP, DoMenuPrintSetup, 
IDM_PRINT , DoMenuPrint , 
IDM_exiT, DoMenuExit, 
I DM_UNDO , DoMenuUndo , 
IDM_CtTT , DoMenuCut , 
IDM_COPY, DoMenuCopy, 
IDM_PASTE, DoMenuPaste, 
IDM_DELETE, DoMenuDelete, 
IDM_FIND. DoMenuFind, 
IDM_REPLACE, DoMenuReplace , 
IIM_FONT, DoMenuFont, 
IDSLCOLOR, DoMenuColor, } ; 



VOID PrintFile (HDC hdc) 
( 

WORD cLine, iLine; 
HANDLE hText; 
PSTR pText; 

WORD maxLine, curLine; 
WORD cur?; 
HFONT hFont; 

i n t ch a rY , pageX , pageY ; 

int horzMarg, vertMarg; 

TEXTMETRIC tm; 

DOCINFO di; 

HCURSOR hPrevCursor; 



// line length, index 

// local heap handle 

// scratch pointer 

// line counters 

/ / current Y coordinate 

// non-prop, font handle 

/ / char & page Y dimensions 

// page margins 

// info about font 

// used by Startpoc 

// save old cursor handle 



// initialize documenc info ytrucfeure for StartDoc 
di.cbSize = sizeof (DOCINFO) ; 
di . IpszDocName = szFileName; 
di . IpszOutput = NtrLL; 

// get memory block handle, convert to pointer, get number of ii: 
hText = (HANDLE) SendMessage (hEdit, BM_OE T HANDLE . 0, 0L) ; 
pText = LocalLock (hText ) ; 

maxLine = (WORD) SendMessage(hEdit, EM_GETLINECOONT, 0, 0) ; 



if (maxLine ■■ 



LocalUnlock<hText) ; 
return; 



//if there's nothing to 
// print, unlock memory 
/ / block and. bail out now 



) 



GetTextMetrics {hdc, &tm) ; // get various dimensii 

charY = tm, traHeight + tm. tmExternalLeading; 

pageY = GetDeviceCaps(hdc, VERTRES) ; 

horzMarg = GetDeviceCaps (hdc, LOGPIXELSX) / 2; 

curY = vertMarg = GetDeviceCaps (hdc, LOGPIXELSY) / 2; 



// DoMenuPrintSetup -- process File-PrintSeti^ c<»iimand from n^nu bar. 
// 

LONG DoHenuPrintSetupiHWND hWUd, WORD wHsg, WORD wParam, LOHS IPar^) 



PRIKTDLG pd; 



// used by coiranon dialog 



// get old cursor handle, change cursor to hourglass 
hPrevCursor = SetCursor (LoadCursor (hinst , IDCJWAIT) ) ; 



StartDoc (hdc, &di) ; 
StartPage (hdc) ; 



// begin the print job 



memset(&pd, 0, sizeof (PRINTDLG) ) ; 
pd. lEtructSize = sizeof (PRIKTDLG) ; 
pd , hv.TidOwner = hWnd; 
pd. Flags = PD_PRINTSETDP; 

PrintDlg(6pd) ; 
return ( 13 ) ; 



// zero out entire structure 
// length of structure 
// owner window 
// option flags 

// display print setup 
// common dialog 



// print contents of edit control, line by line 
for(curLine = 0;. curLine < maxLine; curLine++J 
{ 

// get character index and length for current line 

iLine = (WORD) SendMessage (hEdit, EM_LINEINDEX, curLine, 0) ; 

cLine = (WORD) sendMessage(hEdit, £31_j.lNELElil!?3^, iXilne,. 0) ; 

// now draw the current line using printer device context 
TextOut{hdc, horzMarg, curY, ,&pText [iLine] , cLine) ; 



// DoMenuPrint process Pile-Print command from menu bar. 
// 

LONG DoMenuPrint (HWND hWnd, WORD wMsg, WORD wParam, LONG IParam) 
{ 

PRINTDLG pd; // used by common dialog 



memset (&pd, 0, sizeof (PRINTDLG) J ; 
pd.lStructSize = sizeof (PRINTDLG) ; 
pd.hwndOwner - hfitod; 



// zero out entire structure 
// length of structure 
// owner window 



pd. Flags = pD_RETqBKDG | eD_NOPAGEaroMS // Option flags 

I PD_N0SELECTION [ PD^KOSE-ECTION ' PD_HIDEPRINTTOFTLE ; 



curY += charY; 

if (curY >= pageY 
{ 

curY = vertMarg 
EndPage(hdc) ; " 

} 



EndPage{hdc) ; 
EndDoc (hdc) ; 



vertMarg) 



// advance down page 
// reached end of page? 



// yes, reset Y coordinate 
// and force new page 



// send final new-page 
// and end the print job 



if (PrintDlg{icpd) ) 
.{ 

PrintFile (pd.hDC) ; 



// display print conroon dialog 
// print text in edit control 



SetCursor (hPrevCursor) ; 
LocalUnlock (hText) ; 
return; 



/ / restore old cursor shape 
// unlock edit control 
// memory block & return 



f^fov 4L-Tliese are extracts from the source code for DLGDEIIII04.G; they show the routines specific to the program's printing and printer setup functionaiily. 



time, and prints each line with a call to 
TextOut(). PrintFileO maintains a "cur- 
rent Y coordinate" for the page, incre- 
menting this coordinate by the character 
cell's vertical size as each line is printed 
and resetting the coordinate and request- 
ing a new page when the lower limit of 



the page is reached. After all lines have 
been printed, PrintFile() calls EndPage() 
and EndDocO to eject the last page and 
terminate the print stream. In order to 
keep the source code simple, I haven't 
shown the code associated with tab ex- 
pansion, font selection, or error handling. 



or with the Cancel dialog window. 

THE IN-BOX Please send your ques- 
tions, comments, and suggestions to me 
at any of these electronic-mail addresse 

PC MagNet: 72241.52 
MCI Mail: rduncan 
BIX: rduncan □ 
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